Configuring Export: Flow-Cal Data CFX Commands

CygNet Measurement > FMS Explorer > Commands Menu > Managing Node Commands > Export: Flow-Cal Data CFX

Configuring Export: Flow-Cal Data CFX Commands

Note: This command is provided as an optional feature. For this command to function, several requirements must be met.

If installed, use the Export: Flow-Cal Data CFX command to export raw batch and/or periodic data records for a defined time range from FMS to a specified directory location as a .cfx file. Data that is not from a raw data source, e.g. has been imported into FMS via .csv files (categorized as a "User file" source), is not included in the export.

When the Export: Flow-Cal Data CFX command is executed, batch and/or periodic data is resolved for each eligible device via the customizable command definition file (CDF), and the FMS Service exports the raw data records, created within the specified command time window, to the specified directory location as a .cfx file.

Note: It is strongly recommended that the specified time range for the command include only record spans with fully collected data.

CFX export files retain the units associated with the collection of the raw data whenever possible. In certain circumstances, the FMS system will convert the units to achieve consistency. This could include cases such as the following.

The supplied raw data units are not supported by Flow-Cal.
The raw data comes into the system in a different unit set than previously processed data of a similar type.

See FMS Commands and Flow-Cal Data CFX for more information about using this command via CygNet Explorer (MSS).

See Scheduling FMS Command Tasks in the MSS for more information about scheduling commands.

See FMS ActiveX Controls and CxHmiFms for more information about using commands via FMS ActiveX controls on CygNet Studio or CygNet Vision screens.

See CxFms for more information about scripting commands.

Command Requirements

To enable the command to export raw data to Flow-Cal .cfx files, and see the command listed in command management options, the following elements must be present.

Flow-Cal Export DLL - CygNet Measurement provides an optional DLL file that must be installed on your system to support data exports from FMS to Flow-Cal. The file (CxFmsFlowCalExport.dll) must be installed and registered in the CygNet\Support folder on the computer hosting your FMS service. See Installing CygNet Measurement for more information about installation and registration of the export DLL file.
Flow-Cal Export CDF - CygNet Measurement provides a command definition file (CDF) that must be installed on your system to define how your raw batch and/or periodic data is exported from FMS to Flow-Cal .cfx files. The CDF contains the data item mappings necessary to execute the export command to the corresponding Flow-Cal file version and type, and can be customized to define how the data items are handled. The specific CDF file (ExportFlowCal.cdf) must be included in the CygNet\Services\FMS\CommandDefs folder on your host server. See Installing CygNet Measurement for more information about installation and registration of the export CDF file. See Editing or Customizing the Command Definition File for more information about using and modifying the CDF file.

Note: Refer to Flow-Cal documentation and/or contact your Flow-Cal representative for the most current information about differences between CFX versions, and specific Flow-Cal configuration details.

Configuring an Export: Flow-Cal Data CFX Command

If desired (optional), first edit or customize item mappings in the command definition file.

Use the following procedure to configure Flow-Cal Data CFX exports.

To Configure an Export: Flow-Cal Data CFX Command

Open the Command menu in FMS Explorer.
Click Manage to access the FMS Command Definitions dialog box and then click Add to access the Create New FMS Command Definition dialog box.
Define the command definition properties.

Type a Name for the command into the text box. Maximum character count is 50.
Select the Command type from the drop-down menu.
Select a processing Priority from the drop-down menu.
Select a Logging level from the drop-down menu.
Click to select/clear the check box to Prompt when command runs.

Define the command parameters. The parameters for the Export: Flow-Cal Data CFX command are described in the Command parameters box, which includes the Description, a Required indicator, and a configurable Value field. Set the value for each required and each desired optional parameter, as indicated in its Value field.

Click Create New. The new command will appear in the list of FMS Command Definitions.

Command Definition Properties

The following command definition properties apply to Export: Flow-Cal Data CFX commands.

Property	Description
Name	Type in a Name for the new command.
Command type	Select the desired Command type from the drop-down menu. See FMS Commands for more information about available command types.
Priority	Select a processing queue Priority for the command from the drop-down menu. Options from least to greatest priority are as follows. Low level Medium level High level User initiated transaction Admin initiated transaction Default value is Low level processing queue priority.
Logging	Select a Logging level for the command results from the drop-down menu. Options are as follows. Low - displays errors Medium - displays errors and warnings High - displays errors, warnings, and status Default value is Low level logging when scheduling a command in the MSS. Default value is High level logging when creating or running an ad-hoc command in FMS Explorer.
Prompt when command runs	Click to select/clear the check box to Prompt when command runs. Selecting this option means you will receive a prompt asking if you want to modify the parameters before the command is executed.

Command Parameters

The following command parameters apply to Export: Flow-Cal Data CFX commands when creating or editing commands via FMS Explorer.

Description	Value
Date format	Select the desired time format for data selection, from the drop-down menu. Options are as follows. Device Contract Local Default value is Device time.
Start date/time	Select the beginning date and time of the range for which to export device records. Click ... to access the Select Date and Time dialog box. Note: It is strongly recommended that the specified time range for the command include only record spans with fully collected data. See Selecting Date and Time for more information. See Note below this table. This parameter is required.
End date/time	Select the ending date and time of the range for which to export device records. Click ... to access the Select Date and Time dialog box. Note: It is strongly recommended that the specified time range for the command include only record spans with fully collected data. See Selecting Date and Time for more information. See Note below this table. This parameter is required.
Directory to export file	Enter the directory location to which the file will be exported. Type the directory location for the file into the text box or click ... to access the Browse For Folder dialog box, browse to the directory location, and then click OK. Note: The directory specified is relative to the client computer. This parameter is required.
Export directory format	Select a file directory format for the .cfx export file, from the options in the drop-down menu. Options are as follows. Directory for each polling facility Directory for each device Single directory for all devices This parameter is required.
Name of export file	Select a file name format for the .cfx export file, from the options in the drop-down menu. Options are as follows. Date the export file was created Date of first export history value Node name This parameter is required.
PM data requirement	For periodic data, select whether to export periodic metering data, from the options in the drop-down menu. Options are as follows. Always export Never export Required to perform export (See *Note below this table) This parameter is required.
PQ data requirement	For periodic data, select whether to export periodic quality data, from the options in the drop-down menu. Options are as follows. Always export Never export Required to perform export (See *Note below this table) This parameter is required.
Batch data requirement	For batch data, select whether to export batch data, from the options in the drop-down menu. Options are as follows. Always export Never export Required to perform export (See *Note below this table) This parameter is required.
Event data requirement	For periodic data, select whether to export event data, from the options in the drop-down menu. Options are as follows. Always export Never export Required to perform export (See *Note below this table) This parameter is required.
Alarm data requirement	For periodic data, select whether to export alarm data, from the options in the drop-down menu. Options are as follows. Always export Never export Required to perform export (See *Note below this table) This parameter is required.
Product data requirement	Select whether to export product data, from the options in the drop-down menu. Options are as follows. Always export Never export Required to perform export (See *Note below this table) This parameter is required.
Config data requirement	For periodic data, select whether to export configuration data, from the options in the drop-down menu. Options are as follows. Always export Never export Exclude from export if missing events Note: Be careful to require Configuration data only if the Node supports history data types that utilize configuration data. If selected for a Node where the supported history types do not utilize configuration data (e.g. Node supports Batch history, but not periodic history) any commands that try to retrieve configuration data will fail since it does not exist. This parameter is required.
File format version	Select the version of the .cfx file created for the export, from the options in the drop-down menu. Options are as follows. 8.3.1 (supports batch and periodic data) 8.0.6 (supports batch and periodic data) 7.0.6* (supports batch and periodic data) 5.1 (supports periodic data) *7.0.5 is still supported, although 7.0.6 is provided in the CygNet sample file. Click OK. Note: Alternatively, file format version can be configured in the .cdf (command definition file) if desired. This parameter is required.
Data exported flag	Select whether to flag device records as "exported" in the database, from the options in the drop-down menu. Note: When a "Use flag" option is selected, the Data Exported flag is applied to the entire record, regardless of how many data type(s) are selected for export. Options are as follows. Ignore flag Use flag; always update Use flag; only update if data complete* *Note: When this option is selected, the Data Exported flag is set only for records that contain data, and for which data collection (all supported types) is complete. When exporting partial records (e.g. you are only exporting PM data at this time), it is recommended to use the "Ignore flag" option, preserving the option to flag the record at a later time, when the remaining record data types are exported. This parameter is required.

Note: When using relative (rather than absolute) date/time, if both the start and end date/time have hour, minute, and second values of 00, or if both are set to midnight, an additional day will be added to the date at the end of the range. This occurs because the service assumes the start of the day for the starting date/time and the end of the day for the ending date/time in these circumstances. Therefore requesting a time range from T to T will yield one day of data, and from T-1 to T will yield two days of data. If only one day of data is desired when using relative date/time, the start and end date/times must therefore be the same. If any of the start or end date/time hour, minute, or second values are specified as a value other than zero (or midnight) however, the range will be used as specified.

*Note: If this option is selected and no associated history data is available (Collection Details value does not equal [blank]), the command will fail and no CFX file will be created. See Collection Details in the CygNet Measurement Concepts topic for more information.

Editing or Deleting an Export: Flow-Cal Data CFX Command

See Managing Node Commands for information about editing or deleting this command.

Running an Export: Flow-Cal Data CFX Command

See Running Node Commands for information about running this command.

Editing or Customizing the Command Definition File

If you want to change specific data item mappings, use the following procedure to edit or customize the command definition file (CDF), before executing the Flow-Cal CFX data export command.

Note: When you override a CDF mapping, you generally want to ensure that each newly mapped item is mapped to a field that uses the same unit type as the new item. If you decide to map an item requiring units to a unitless field in the file however, the mapping will still be valid - but the value reported from the device will appear exactly as read, and will not be associated with a unit set. Values are not converted in the file when they are sent to a unitless field.

On your host server, in the CygNet\Services\FMS\CommandDefs folder, find the ExportFlowCal.cdf (command definition) file. Verify that the word "Sample" has been removed from the file name (this was likely already done at installation of the CDF) so that the file will be recognized by the FMS service, and then open the file.
Locate the FlowCalCommand section of the file corresponding to the correct Flow-Cal CFX file version for the export, e.g. 8.0.6.

Optionally add, verify or edit the TimeOrientation value to align timestamps as desired. Options are Leading (all records oriented to the beginning of the record span), Trailing (all records oriented to the end of the record span), or Native (records oriented as configured at the device). Default behavior is Native time orientation.

Note: The Leading or Trailing time orientation override is unable to adjust to handle Daylight Saving Time (DST) changes that originate from the device.

If used, include the TimeOrientation element in the CDF as in the following example.

. . .

Edit data item mappings and/or values as desired, within each section of the file. See EFM Data Items (FMS Alarm Items, FMS Batch Items, FMS Configuration Items, FMS Event Items, FMS History Items, and FMS Product Items) in the Devices section for more information about specific items pertaining to each section.
Some items are mapped using a MultiField, that accommodates multiple item mappings. Edit MultiField mappings as desired.
1. List the preferred Flow-Cal field first (e.g. <LowFlowCutoffSetPoint>) within the MultiField section.
2. Within each Flow-Cal field, list the preferred FMS data item mapping first (e.g. eFMS_CFG_LOW_FLOW_CUTOFF_PULSE_INTERVAL).
Each MultiField mapping only populates the first Flow-Cal field found (e.g. <DifferentialPressure>), and uses the first valid FMS data item value found (e.g. eFMS_PV_DIFF_PRESSURE) out of all FMS data item enumeration strings listed. Once a valid value is found, that value will be used and processing will continue beyond that MultiField section.
Additionally, if you associate a mapped item in a MultiField with a specific device type (orifice, cone, turbine, etc.), the mapped item will then only be exported if the meter type is correct and the item value is valid.
Sometimes multiple items map to the same field, that accommodates only one item mapping. In this case the first value found in the CDF file with a corresponding valid value will be used. For example, when mapping KFactor values to the field provided, the value returned (e.g. eFMS_CFG_GAS_K_FACTOR_MASS, eFMS_CFG_LIQUID_K_FACTOR_VOLUME, etc.) maps to the same field, so the first mapped value will be used.
Edit custom periodic data item mappings as desired. Custom FMS items can be mapped to the following Flow-Cal fields.
- In v8.3.1, v8.0.6 or v7.0.6, in the <Configuration> section:
- Flow-Cal fields UserCharacteristic1 through UserCharacteristic10 can have mappings of any FMS configuration item that resolves to a string value. By default, FMS Configuration items eFMS_CFG_CUSTOM1 through eFMS_CFG_CUSTOM10 are initially mapped to these fields.
- Flow-Cal fields UserAttribute1 through UserAttribute20 can have mappings of any FMS configuration item that resolves to a string value. Alternatively, they can have mappings of any valid FMS token containing facility information (RemoteDeviceType, PollingFac_Attr0 through PollingFac_Attr29, PollingFac_Table0 through PollingFac_Table29, or PollingFac_YesNo0 through PollingFac_YesNo19).
- In v8.3.1, v8.0.6 or v7.0.6, in the <History> <Common> section (applies to gas or liquid devices):
- Flow-Cal fields UserDefined01 through UserDefined08 can have mappings of any valid FMS PV item.
- Flow-Cal fields UserDefined01 through UserDefined05 have default mappings of FMS History items eFMS_PV_PM_CUSTOM1 through eFMS_PV_PM_CUSTOM5.
- In v5.1, in the <History> section:
- Flow-Cal fields UserFields1 through UserFields8 can have mappings of any valid FMS gas PV item.
- Flow-Cal fields UserFields1 through UserFields5 have default mappings of FMS History items eFMS_PV_PM_CUSTOM1 through eFMS_PV_PM_CUSTOM5.
Edit custom batch item mappings as desired. Custom FMS data items can be mapped to the following Flow-Cal fields.
- In v8.3.1, v8.0.6 or v7.0.6, in the <CustomBatchData> section:
- Flow-Cal fields CustomString01 through CustomString08 can have mappings of FMS Batch items with string values. Numeric values or numeric and non-numeric strings can be processed successfully when mapped to these fields.
- Flow-Cal fields CustomNumeric01 through CustomNumeric08 can have mappings of FMS Batch items with numeric values. Only numeric values or numeric strings can be processed successfully when mapped to these fields.
- Flow-Cal fields CustomDate01 through CustomDate04 are not supported for FMS mapping.
Save and close the edited ExportFlowCal.cdf file.

Note: Problems that arise while processing a command definition file are logged to the Services > FMS log file.